<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	
	<head>
		<meta http-equiv="Content-Language" content="en-gb" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="description" content="Images and stencils" />
		<title>PDF Graphics .NET documentation - Images and stencils</title>
		<link rel="stylesheet" href="../style/Help.css" type="text/css" />
	
	</head>
	
	<body>
		<div class="navigator">
			<span>
				<strong>PDF Graphics .NET</strong> :: <a href="..\Index.html">Help</a> :: <a href="..\Painting_graphics.html">Painting graphics</a> :: Images and stencils
			</span>
		</div>
		
		<h1>Images and stencils</h1>
		
		<p>
			This section covers the following topics:
			<ul>
				<li><a href="#Images">Images</a></li>
				<li><a href="#Stencils">Stencils</a></li>
			</ul>
		</p>
			
		<h2><a name="Images"></a>Images</h2>
		
		<p>
			To create an image, use the <span class="code">Image</span> class and supply a path to a file containing the image. The file is
			then parsed to determine the image's dimensions and other properties required to render the image.
		</p>
	
		<p>
			Drawing images onto a graphics surface is done through a single method call on the <span class="code">Graphics</span> instance,
			<span class="code">DrawImage</span>. This method accepts an image and a destination
			rectangle to draw the image into. This rectangle determines the size of the image on the page as well as its location.
			Images that are not originally of the same size as the destination rectangle will be scaled.
		</p>

		<div class="sampleCode">Image myImage = new Image("Kitten.jpg");
g.DrawImage(myImage, new Rectangle(10, 10,  100, 100)); 
g.DrawImage(myImage, new Rectangle(10, 120, 100, 100));</div>
	
		<p>
			In the example above, an image is created based on the file <span class="code">Kitten.jpg</span>. It is then drawn onto the page
			twice.
		</p>
		
		<p>
			Images are embedded into the PDF document. It is therefore advised not to use excessively large images as this will increase the
			size of the output PDF. If an image is drawn twice or more onto a page, or across pages, it will be embedded only once.
			Creating multiple <span class="code">Image</span> instances with the same path will also cause the image to be embedded only once,
			and reused across the instances. For example:
		</p>
		
		<div class="sampleCode">Image myImage = new Image("Kitten.jpg");

g.DrawImage(myImage, new Rectangle(10, 10, 100, 100));

g.NewPage();
Image second = new Image("Kitten.jpg");
g.DrawImage(second, new Rectangle(10, 10, 100, 100));</div>
			
		<p>
			The resulting PDF file will contain the <span class="code">Kitten.jpg</span> file only once.
		</p>
		
		<p>
			The only image file format currently supported by PDF Graphics .NET is the JFIF
			(<span class="code">.jpg</span>) format. A file that is not recognised as a JFIF file will be refused.
		</p>
		
		<h2><a name="Stencils"></a>Stencils</h2>
		
		<p>
			A stencil is a reusable graphic that is defined once and used once or more times across a document.
			Stencils can use any graphic primitive that a PDF page supports, including further stencils. To create a stencil,
			use the <span class="code">CreateStencil</span> method on the <span class="code">Graphics</span> class. To paint
			contents onto a stencil surface, use the <span class="code">Graphics</span> property of the <span class="code">Stencil</span>
			instance.
		</p>

		<p>
			Painting a stencil is done through the <span class="code">DrawStencil</span> method of the <span class="code">Graphics</span>
			class. This works for pages as well as for stencils themselves. See the following example:
		</p>
	
		<div class="sampleCode">GraphicsPath path = new GraphicsPath();
path.AddLine(  0.0f,    0.0f,    6.0f,  12.0f);
path.AddLine(  6.0f,   12.0f,   19.0f,	13.8f);
path.AddLine( 19.0f,   13.8f,    9.7f,	23.2f);
path.AddLine(  9.7f,   23.2f,   12.0f,	36.0f);
path.AddLine( 12.0f,   36.0f,    0.0f,	30.0f);
path.AddLine(  0.0f,   30.0f,  -11.6f,	36.4f);
path.AddLine(-11.6f,   36.4f,   -9.4f,	23.0f);
path.AddLine( -9.4f,   23.0f,  -19.0f,	13.8f);
path.AddLine(-19.0f,   13.8f,   -6.0f,	12.0f);
path.Close();

Stencil star = g.CreateStencil(40, 40);
star.Graphics.FillPath(Rgb.YellowBrush, path, 20, 0);
star.Graphics.DrawPath(Rgb.RedPen, path, 20, 0);

g.DrawStencil(star, 40, 40);
g.DrawStencil(star, 70, 80);
g.DrawStencil(star, 20, 100);</div>
		
		<p>
			The above code defines a stencil with a yellow filled star graphic, and paints it three times onto a page:
		</p>
		
		<img src="../images/Stencil_stars.jpg" />
		
		<p>
			Stencils can contain other stencils. Practicality aside, there is no limit to the levels of nesting. Using the star
			stencil used in the example, above, the following example creates a new stencil that is composed of a ring of stars.
		</p>

		<div class="sampleCode">Stencil ring = g.CreateStencil(400, 400);
ring.Graphics.TransformTranslate(200, 200);
double increment = Math.PI / 6f;
for (double angle = 0; angle < Math.PI * 2; angle += increment)
{
    ring.Graphics.DrawStencil(
        star, 
        (float)Math.Cos(angle) * 150f, 
        (float)Math.Sin(angle) * 150);
}

g.DrawStencil(ring, 100, 100);</div>

		<img src="../images/Stencil_Ring.jpg" />
		
		<h3>Notes</h3>
		<ul>
			<li>
				Calling <span class="code">CreateStencil</span> on a stencil's <span class="code">Graphics</span> instance
				is allowed; the new stencil will be embedded in the PDF document just like the first.
			</li>
			<li>
				Stencil content may contain resources such as fonts and images. These will be embedded in the PDF document
				just as if they were used directly on a page.
			</li>
			<li>
				There is no need to fully define a stencil before using it; as long as the stencil is defined
				before the main <span class="code">Graphics</span> instance is closed, it can be used on pages.
				In other words, you can create a stencil with <span class="code">CreateStencil()</span>, and
				draw it onto pages using <span class="code">DrawStencil()</span> calls, without having painted
				anything onto the stencil's <span class="code">Graphics</span> instance.
			</li>
		</ul>
		
		<h3><strong>Navigation options:</strong></h3>
		<p><a href="Text_fonts_styles.html">&lt; Text, fonts and text styles</a> | <a href="Transformations.html">Transformations &gt;</a>
		
	</body>
	
</html>